Implementing Drag and Drop Functionality

In IDL versions 6.3 and later, you can create applications that allow users to drag tree nodes from a tree widget to a draw widget. Drag and drop functionality is not enabled by default. When creating an IDL application that incorporates both a tree widget and a draw widget you can enable drag and drop behavior to drag values from the tree widget to the draw widget. This section discusses the steps necessary to implement drag and drop functionality in your application.

Implementing drag and drop functionality in your application entails three steps:

1. Making Nodes Draggable. You must explicitly specify that a node or group of nodes in the tree widget can be dragged. See Dragging and Dropping Tree Nodes for details.
2. Responding to Drag Notifications (Callbacks). When the user drags a tree node onto a draw widget, IDL generates a notification, which is passed to a callback function. In most cases, you can use the default callback function, but you can create your own callback function to handle special or complex situations. Drag notifications allow you to control if and where drops are allowed.
3. Responding to Drop Events. When the user releases the mouse button to drop the selected nodes, IDL generates a drop event. You can use the information contained in the drop event structure to perform an operation, such as loading an image or other visualization in the draw widget.

Responding to Drag Notifications (Callbacks)

When the user drags a group of selected nodes over a draw widget, IDL automatically calls the routine defined as the drag notification callback for the draw widget. The purpose of the drag notification callback is to provide the widget system with information about where dragged nodes can be dropped, allowing it to change the cursor display to indicate to the user whether nodes can be dropped at the current position. You, as an IDL application programmer, cannot respond to the value returned by the drag notification callback directly, but you can choose to specify your own version of the callback function to override the default behavior. Drag notification callbacks are specified via the DRAG_NOTIFY keyword to WIDGET_DRAW, or the SET_DRAG_NOTIFY keyword to WIDGET_CONTROL.

Drag notifications are also generated when the state of a drag modifier key changes (either up or down). If you override the default drag notification callback, you can use this information to update the drag cursor with a plus symbol (+).

If no callback is defined for the draw widget, the default callback will be used.

Drag Notification Callback Return Values

The drag notification callback function returns an integer value calculated by performing an OR operation on the following values:

Value	Meaning
0	User cannot drop
1	User can drop above
2	User can drop onto
4	User can drop below
8	Show the plus indicator

For example, if the callback returns the value 3, the use can drop onto the draw widget and the plus indicator will be displayed.

The Default Drag Notification Callback

The default drag notification callback function is used if no function is specified for the draw widget. The default callback returns 0 if drop events are not enabled (DROP_EVENTS=0) and 1 otherwise.

Writing Custom Drag Notification Callbacks

In most cases, the default drag notification callback should be adequate for an application that allows the user to drop tree nodes onto a draw widget. If it proves inadequate, however, you can create a custom callback to perform extra processing.

The drag notification callback routine has the following signature:

FUNCTION Callback_Function_Name, Destination, Source, $
   X, Y, Modifiers, Default

where

• Callback_Function_Name is the name of the callback function. This value is specified as the value of the DRAG_NOTIFY keyword.
• Destination is the widget ID of the draw widget over which the item is dragged.
• Source is the widget ID of the source tree, from which a list of widget IDs representing the list of selected nodes can be retrieved using the TREE_SELECT or TREE_DRAG_SELECT keywords to WIDGET_INFO.
• X is the position to the right of the lower left corner of the drawable area, in device coordinates (pixels).
• Y is the position above the lower left corner of the drawable area, in device coordinates (pixels).

• Modifiers indicates the state of the modifier keys. The widget system generates them by ORing the following values together for the depressed keys:

  Bitmask	Modifier Key
  1	Shift
  2	Control
  4	Caps Lock
  8	Alt

  Note: For UNIX, the Alt key is the currently mapped MOD1 key.

• Default is the value that the default callback would have returned. A common usage is to have the callback return its value after modifying it to show the + indicator.

The return value should indicate where a drop is allowed to take place relative to the destination widget and whether the “+” symbol should appear with the drag cursor, as described in the table above under "Drag Notification Callback Return Values." For additional information on writing drag notification callbacks, see Dragging and Dropping Tree Nodes.

Responding to Drop Events

When the user releases the mouse button over a valid drop target (that is, when the DROP_EVENTS keyword to WIDGET_DRAW has been set), a WIDGET_DROP event is generated. Your application’s event handler should recognize this drop event and perform some action.

The drop event’s information is contained in a WIDGET_DROP structure. (See DROP_EVENTS in the reference section for WIDGET_DRAWfor a full definition of the WIDGET_DROP structure.) The important components of the structure when responding to drop events are:

• ID: The widget ID of the destination node.
• DRAG_ID: The widget ID of the source tree widget. The selected nodes of this tree are the nodes that are being dragged. You can use the TREE_SELECT keyword to WIDGET_INFOalong with this widget ID to retrieve the list of selected nodes.
• X and Y: The drop position relative to the lower left corner of the drawable area.
• MODIFIERS: An integer representing the state of the modifier keys, calculated by ORing together the values shown in the table under "Drag Notification Callback Return Values" above. On some platforms it is common for the Ctrl key to be used as the copy key, with simple move operations being performed when Ctrl is not pressed.

Draw Widget Drag and Drop Example

The IDL distribution contains an example that contains a tree widget representing various image files and a draw widget onto which the tree nodes can be dragged to display the images.

The draw widget drag and drop example is included in the file drag_and_drop_draw.proin the examples/doc/widgets subdirectory of the IDL distribution. Run this example procedure by entering drag_and_drop_draw at the IDL command prompt or view the file in an IDL Editor window by entering .EDIT drag_and_drop_draw.pro.